/**
 * @file timer_scheduler.h
 * @brief 定时器调度器头文件
 * 
 * 定时器调度器负责管理和执行定时器任务，
 * 包括定时器的添加、删除、更新和触发等核心功能。
 */

#ifndef __TIMER_SCHEDULER_H__
#define __TIMER_SCHEDULER_H__

#include "smart_timer.h"

#ifdef __cplusplus
extern "C" {
#endif

/**
 * @brief 定时器回调上下文结构体
 */
typedef struct {
    void (*callback)(uint8_t timer_id, timer_action_t action, void *user_data);  ///< 回调函数指针
    void *user_data;                                                              ///< 用户数据指针
} timer_callback_ctx_t;

/**
 * @brief 定时器调度器结构体
 */
typedef struct {
    timer_config_t *timers;          ///< 定时器配置数组
    uint8_t max_timers;              ///< 最大支持的定时器数量
    uint8_t timer_count;             ///< 当前定时器数量
    timer_callback_ctx_t callback_ctx; ///< 回调上下文
} timer_scheduler_t;

/**
 * @brief 初始化定时器调度器
 * @param scheduler 调度器实例
 * @param max_timers 最大定时器数量
 * @return timer_err_t 操作结果
 */
timer_err_t timer_scheduler_init(timer_scheduler_t *scheduler, uint8_t max_timers);

/**
 * @brief 反初始化定时器调度器
 * @param scheduler 调度器实例
 * @return timer_err_t 操作结果
 */
timer_err_t timer_scheduler_deinit(timer_scheduler_t *scheduler);

/**
 * @brief 启动定时器调度器
 * @param scheduler 调度器实例
 * @return timer_err_t 操作结果
 */
timer_err_t timer_scheduler_start(timer_scheduler_t *scheduler);

/**
 * @brief 停止定时器调度器
 * @param scheduler 调度器实例
 * @return timer_err_t 操作结果
 */
timer_err_t timer_scheduler_stop(timer_scheduler_t *scheduler);

/**
 * @brief 添加定时器到调度器
 * @param scheduler 调度器实例
 * @param config 定时器配置
 * @param timer_id 返回的定时器ID
 * @return timer_err_t 操作结果
 */
timer_err_t timer_scheduler_add(timer_scheduler_t *scheduler, const timer_config_t *config, uint8_t *timer_id);

/**
 * @brief 从调度器删除定时器
 * @param scheduler 调度器实例
 * @param timer_id 要删除的定时器ID
 * @return timer_err_t 操作结果
 */
timer_err_t timer_scheduler_delete(timer_scheduler_t *scheduler, uint8_t timer_id);

/**
 * @brief 删除调度器中的所有定时器
 * @param scheduler 调度器实例
 * @return timer_err_t 操作结果
 */
timer_err_t timer_scheduler_delete_all(timer_scheduler_t *scheduler);

/**
 * @brief 更新调度器中的定时器配置
 * @param scheduler 调度器实例
 * @param config 新的定时器配置
 * @return timer_err_t 操作结果
 */
timer_err_t timer_scheduler_update(timer_scheduler_t *scheduler, const timer_config_t *config);

/**
 * @brief 设置调度器中定时器的启用状态
 * @param scheduler 调度器实例
 * @param timer_id 定时器ID
 * @param enable 是否启用
 * @return timer_err_t 操作结果
 */
timer_err_t timer_scheduler_set_enabled(timer_scheduler_t *scheduler, uint8_t timer_id, bool enable);

/**
 * @brief 获取调度器中的定时器列表
 * @param scheduler 调度器实例
 * @param timers 定时器配置数组
 * @param count 输入时表示数组大小，输出时表示实际定时器数量
 * @return timer_err_t 操作结果
 */
timer_err_t timer_scheduler_get_list(timer_scheduler_t *scheduler, timer_config_t *timers, uint8_t *count);

/**
 * @brief 获取调度器中指定定时器的配置
 * @param scheduler 调度器实例
 * @param timer_id 定时器ID
 * @param config 返回的定时器配置
 * @return timer_err_t 操作结果
 */
timer_err_t timer_scheduler_get(timer_scheduler_t *scheduler, uint8_t timer_id, timer_config_t *config);

/**
 * @brief 获取调度器中定时器的状态
 * @param scheduler 调度器实例
 * @param timer_id 定时器ID
 * @param enabled 返回定时器是否启用
 * @return timer_err_t 操作结果
 */
timer_err_t timer_scheduler_get_status(timer_scheduler_t *scheduler, uint8_t timer_id, bool *enabled);

/**
 * @brief 获取调度器的运行状态
 * @param scheduler 调度器实例
 * @param running 返回调度器是否正在运行
 * @param timer_count 返回当前定时器数量
 * @return timer_err_t 操作结果
 */
timer_err_t timer_scheduler_get_scheduler_status(timer_scheduler_t *scheduler, bool *running, uint8_t *timer_count);

/**
 * @brief 暂停或恢复调度器
 * @param scheduler 调度器实例
 * @param pause true表示暂停，false表示恢复
 * @return timer_err_t 操作结果
 */
timer_err_t timer_scheduler_pause_resume(timer_scheduler_t *scheduler, bool pause);

/**
 * @brief 重置调度器中的定时器状态
 * @param scheduler 调度器实例
 * @param timer_id 定时器ID
 * @return timer_err_t 操作结果
 */
timer_err_t timer_scheduler_reset(timer_scheduler_t *scheduler, uint8_t timer_id);

/**
 * @brief 检查定时器是否存在于调度器中
 * @param scheduler 调度器实例
 * @param timer_id 定时器ID
 * @param exists 返回定时器是否存在
 * @return timer_err_t 操作结果
 */
timer_err_t timer_scheduler_exists(timer_scheduler_t *scheduler, uint8_t timer_id, bool *exists); 

#ifdef __cplusplus
}
#endif

#endif // __TIMER_SCHEDULER_H__
